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& Te INTRODUCTION 


1.1. SCOPE 

This documents the user interfaces using Library Utilities necessary 
to access or generate library modules or wmanipulste a library in the 
CDI environment. 


Some of the MIRAM library modules supported for the current release 
R9.U are: 


~- saved run library modules (Type J) 


- screen format modules (Type Fy, FC) 
- HELP modules (Type Help) 
- MENUS (Type Menu) 


The SAY Library modules supported for the current release are: 
- source 
- proc 
- object 


- load 


& - groups 








2e FUNCTIONS AVAILABLE 


© The system Library interface allows user programs to directly access 
any system library file. The functions provided are: 


= reading a library module 
- creating a Library moaule 
7 deleting a library module 
- interrogating a Library directory 


- updating Library module header information 
Qete LIBRARY INTERFACES 


2Qetate Interface Macros ; 

The CDI macros are the onty ones used to interface with libraries 
(thru tibrary uttlities). Both imperative and declarative macros are 
used.e The imperatives are: 


OPEN 


data management fite OPEN 
- CLOSE - data management file CLOSE 


- OMINP - retrieve a Library record 


- DMOUT - write a Library record 
@ - DMSEL - initialize a Library operation 
- OMUPD -— change module header information 


The declaratives are: 


~ CDIB - Library operation control btock 


RIB - optionally used only at OPEN 


2ele2e Flow of Control 


The coIBp (Cas defined by data management) #¢s the basic controlling 
block used by Library utilities to communicate with the user programe 
It is referenced on each imperative macro and will contain status on 
ceturne 


The user starts by issuing an OPEN imperative to a CDI3 which identi- 
fies the Library file involved (by LFD). This 4s a standard data man- 
agement requirement. 
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The next step depends upon what kind of operetion the user wants to 
doe The operations available are described in Section 2.2 and assume 
the COI8 is already open. The flow of most operations its: 





4e¢ OMSEL ~ initialize Cor identify) operation 
2 DMINP/DMOUT/DMUPO - retrieve or present data 
3. OMSEL - terminate operation 


Step 2 will probably be executed more than once: ‘Step 3 is now always 
required. 


The user must issue a CLOSE imperative macro for each active CD18 
before the program terminates. CLOSE «ALL fs also acceptable. 


2elde READING AND WRITING LIBRARY MODULES 


Library modules are normally read or written one record at a time (us- 
ing a DMINP of DMOUT imperative). The only exception is when transter 
mode Csee the OMSEL imperative, section 4.1.2?) is used to copy an en- 
tire module. Transfer mode reads and writes 256 byte blocks instead 
of single records. 


Library Utilities supports both fixed and variable Length records. The 
record format is specified in the RIB parameter RCFM. 


Fixed-record lengths are specified by the FYIS parameter RCSZ and may 
vary from 1-72K bytes. Variable-records have the weximum allowed 
Length specified in the R1B and the actual record length in the first 
2 bytes of the 4 byte Record Descriptor word (RDW) as defined by Data 
Management (See CS-14, “Common Data Interface (to Data Management) 





Z2e2ete Reading Library Module Records 

1. DMSEL cdibname] (1) 11,LIS,IN»workareal(O) {0 

2e DAINP cdibname!] (1) ]1,workarea[ (0) 10 

OMSEL initializes the operation and locates the module by the name and 
type in the workarea (see section 264). OMINP moves tigta records, one 
at a time, to the user buffer. The user issues as many as needede Erm 
rors and end-of-data are signated in the appropriate COI fietds. 
2.22252 Writing Library Module Records 


1. DMSEL cdibname](1)J$1,LIB,OUT»sworkareaf{ (0310 


2 — DMOUT cdibname!l (1211, workareal{ C0340 
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3. OMSEL cdibname][(1311,L1B,ADD 


The first OMSEL Cout) initializes the operation and specifies the name 
and type of the module being yenerated. CMOUT adds records sequen~ 
tially to the end of the file. The user issues as many as needed. The 
last DMSEL (ADD) completes the operation by updating the necessary di- 
rectory indices to tnclude the new module and end-of-library CENODLIB)D 
marker. If a module exists with the same name and type, it is delet- 
ede 


» 


2edse. DELETING A LIBRARY MODULE 

OMSEL cdibnanel(1)I1,LIB,ZDEL,workareal (9) 10 
OMSEL initializes the operation and tocates the module specified by 
the name and type in the workareae- The mocule its marked deleted but 
not physically removed from the file until it is copied or packec. If 


no module satisfying the search criteria (full nane and type must be 
specified) an error condition is returned. 


204. SEARCHING A LIBRARY DIRECTORY 


2e4e.4- Specific Module Search 
The tibrary directory can be searched for a specific nodule by using 
a 12 byte key consisting of 8 bytes of name and 4 bytes of type, both 
padded with blanks as necessary. 
Examples 

IMYMOD Is I 

{0 718 #411 
2e4a2~ Gang Module Search 
Library Utilities also permits searches based on partial name and/or 
partial type. This ts called a “gang” searche Partitat names and 
types are padded with binary zeroese 


Examples 


ImyooooD0000000 TT YOOOO] 
10 718 411 


where OO stands for x700%. The search is for any wodule with a 
name beginning “my~ and a type beginning “TY”. 


If the module name or type does not matter, a x~007 is placed tn the 
first position of the appropriate key field. 


1 j cm 
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Examples 


[)000000000000000IF | 


{. 718 114 
where OO stands for x700%. The search ts for any aodule whose 
type is “F*. 


lf the entire key is X700%s, Library utilities will accept any module 
found in the file. : 
2.4236 Performing a Library Directory Search 
The required sequence of imperative macros is: 

1. DMSEL cdib,LIB,HIN, (9) 

2e where RO points to the i2-byte module keye 
DMSEL initializes the operation, 

DMINP retrieves the header of the first (next) module whose name and 
type key satisfies the search criteria, and puts it in the workarea 
specified by RO. This imperative may be repeated as often as desired 


and will set the end-of-file condition tin the CDIS when no more 
modules satisfying the search criteria are found. 





2e5e CHANGING LIBRARY MODULE HEADER INFORMATION 

4. DMSEL cdibname](1)[1,LIB,HIN, workareaf (10 

Ze OMINP cdibname] (1) }1,workareaJ] (0) [9 

3. Make desired changes to header namey type, or comment fields. 

&e DMUPD cdibname] (1)]1,workarea] (0) 10 

DMSEL initi?alizes the operation. DMINP Locates the module and returns 


tts header record; if no module is tounds an error jis returnede The’ 


user alters the name, type, or comment fields as desitred and then 
writes the altered header and updates the directory with a DHUPD com- 


mande If the new module name and type matches an existing module name 
and type, the change operation is suppressed and an error is returned. 
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ry : — 3- DESIGN TRADE-OFFS AND PRODUCT OBJECTIVES 


The goals in providing library utilities through a COY intertace re 
are: 


1. To provide a standard library interface consistent with other 
data management interfaces. We can eventually allow users to use 
library utilities (which we never have had before). The inter- 
face is easily learned as it is a derivative of the CpDI system 
standard. 


2- To provide device independence for Sequential source INPUT/OUTFLT 
userse Some of the special commands (such as CONSFL module name 
for input) should be optionally performed automatically as part 
of OPEN. This would require more information cn the job control 
device allocation sete It woutd allow users to use the same rou- 


tine to read/ write from .either a sequential device or a Library 
element. 





























BS EO Se SE Eee eee 






Sg-e] | COI Library User Intertace l 1 | 4-1 
Number } 30 SEP 82 | Update |] Page 
@ 4. INTERFACE DESCRIPTION 


4ele USER INTERFACE 
Kole Declarative Macros 


41.121. CDIB Macro 


The CdI18 is the controlling block for any library operation in pro- 
gress» Its use and format are defined in CS-14, “Common Data Inter- 5 
face (to Data Management)". 


4121.2. RIB Macro 


The RIG (Resource Information Block) is used to present Library UtiLi- 

“ties with information regarding the file structure and the users en~ 
vironment. The subset of RIA parameters pertaining to tibrary file 
eccess is shown betow; a full description of the R13 macro can be 
found in CS-14 “Common Data Intertace (to Data Management)". 


Format: 


Label RIB C,ACCESS={EXCISRDOD} 

T,LIBADO={(NOT YES) 
C,LIBINIT=(NOLYES}23 
U,MODE={SEQIRAN}] 

& CyNWAIT=(NOLYES)) 
CSRCFM=CEJ KI VARIS 
C,RCSZ={(2564n)] x 
C,RECPASS=(NOIYES}I] » 
C,SKAD=SYMBOLJ * 
CpWKFM={NOITVARIVARIDI 


ACCESS Specifies the type of file sharing permitted: 


EXC Onty 4 access path to the file is permitted 
at any times This path has exclusive read/ 


write use of the file. CThis js the 
default}. 
SRDO Multiple access paths to the file are permit- 


teds, but only to cead. Write operations are 
not atlowed. 


LIBAOD Specifies that an automatic DMSEL CADDD is to be done 
when the file is CLOSéd. : 


LISINIT Specifies that the file is te be inftfhaiterd chen se 





ACDE* 


NWAIT 


RCFM 


RCSZ* 


RECPASS* 


SKAD* 


WK FM 








Specifies SEQuential or RANdom access to the fite. 


Specifies whether the task should be waited when a file 
share environment incompatibility occurse (See the AC 
CESS para- meter). 


Specifies the record format. 
FIX fixed length records 


VAR variable length records. The RCSZ parameter 
gives the maximum allowable record size. The 
tirst 4 bytes are the record descriptor word 
CRDW, see CS-14). 


For fixed records, this is the record size in bytese 
For variable records, this is the maximum allowable re- 
cord size. 


Specifies if record boundaries are ignored when reading 
a tile. “‘NO™ will cause LU. to start each input oper- 
ation at the beginning of a record. : 


The Location of a fullword which contains the module 
relative record number when reading randoaly 
(MODE=RAN). The first record in the module is relative 
record te 


Specifies the workarea format as fixed or variable (4 
byte record descriptor word followed by data). jhe 
workarea format may be different from the record for- 
mate 


NO The workarea and record formats are identi- 
cal. (This is the default)e 


VAR The workarea format is variable. For outputs 
the user must specify the effective record 
size in the first haltword of the ROW. On 
input, LeU. will put the record size in the 
RDWe The workarea must be large enough to 
hotd the largest record which might be re- 
turned. 


VARI Same as VAR for output operations. On inputs 
the user requests a number of bytes to be 
moved in the ROW. If the record its longer 
than this amount, the record is truncated and 
the CDIB wilt reflect this. If the record is 
too short, LeUe. with alter the RDW to hotd 
the correct record lengthe 
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@ xThese parameters are for MIRAM Library files only. 
4ele20 Imperative Macros 


Sele 2ele DOMSEL Macro 


OMSEL Ccdibname}](1)11) 
sLIB 
»CADDIJDELEHINLININEXTIOUTIXINTXOUT) 
»{workareal (0) 10) 


Positional parameters 1 and 4 are described in CS-14 “Common Data In- 
terface (to Data Management)". 


' 


Positional parameter 2 indicates that this directive pertains to a Li- 
brary file and Library Utilities should be activated. 


Positional parameter 3 gives the type of action to be done: 


ADD °»~—sCOcrreate a directory entry for the current module and add it 
to the file. Positional parameter 4 does not applye 


DEL delete the module whose name and type key appears tn the 
workarea. 


HIN initialize the input operation to return oniy module head- 
ers. Search criteria are specified in the workarea (see 
& section 2.4). 
IN initialize the input operation to return mouuie records. 
NEXT initiatize the input operation for the next module in file 


with a mame and type key satisfying the search criteria 
previously specified on the DMSEL in macro {see section 
204). 


ouT initialize the output to write module records to the end 
of the tile. Yhe modute name and type key is specified in 
the workarea. 


XIN initialize the transfer mode input operation. Cach subse~ 
quent DMINP with return a 25$-byte block tros the module 
beyinning with the module header-e It must be paired with 
XOUT for output. 


XOUT initialize the transfer mode output cperatione Each 
subsequent DMOUT will write a 25é6-byte olock to the file. 
LeU. expects the first block to contain the module header. 
It must be paired with XIN for input. 
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In each operation where a mame and type key is referenced, a 12-byte 
contiguous area consisting of an 8-byte nawe and 4 byte type fields is 
expected. (See section 2.4). 


bele2e2e = DMINP/DMOUT Macros 


The ODMINP reads and DMOUT writes records Cor blocks in the case of 
transfer mode) to or from the file. Both are described in CS-14 "Com- 
mon Oata Interface (to Data Management)”. 


4.2. OPERATOR INTERFACES 


N/A 


43. DATA BASES 


The proposed structure of the MIRAM Library file will be presented in 
an appendix. 


The definition of the SAT Library file structure exceeds the scope of 
this document. 
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e. iy tee ee eee aa : 5. ENVIRONMENT CHARACTERISTICS 


Sete HARDWARE REQUIRED 


Unk nowne 


5e2e RESTRICTIONS 


The MIRAM Libraries Cand Library utilities) exist only in the COI en- 
vironments MIRAM Libraries will be inaccessable in the DTF onty sys- 
teme 


5032 COMPATIBILITY 


N/A 
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Ee ARM 


To be suppliec. 





























- oe | CDI Library User Interface te 1 7-4 
number @D } 30 SEP B2 , deed bene 


eee ee ee we we we me we wm we ae me we we ee we wm we we a we we ee we we ee ee ee ee we we se we ee ee ee ee ee ae ee ee ee ie ee ee 


@ eee ne, ee 7e PERFORMANCE a re ee 


To be supplied. 
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APPENDIX Aw PROPOSED STRUCTURE FOR MIRAM LIBRARIES: 


format for MIRAM library files is based on the Natlos-Holt- Sny- 
etters (10/17/72 - 11/20/75). 


DATA PARTITION 


ata partition will consist of 255 byte fixed length non-keyed re- 
~ Neither deleted records nor mixed keyed/non~-keyed records will 
ede It is felt that neither feature is required and their tnclu- 
would require a one byte record control block fRCB) im each re- 
The RCB would break otherwise contiguous text data (for block 
es) and unnecessarily complicate the designe 


ule consists of a set of contiguous blockse The first block is 
eader block, which occupies one full block and contains the num- 
of blocks consumed by the module. The next btiocks contzein tke 
e datas ALL pointers within tne header which point to blocks 
n the module are retative to the module header itself. Copying 
odule from one file to another can be block for block without 
ication. 


first module will be written starting in the first block cf the 
partition, followed by an ENDLIB block. When a second module ts 
ed, its header will be written to the same block as the ENDLIB 
a new ENDLIB block will be written at the end of the module. 

should only be one ENOLIB block in every fttiée T¥ this ts not 
ase, the file is considered corrupted. 


eader block format is the same for all modules types as well as 
0G records and contains these fields: 


Module name 
= Module type 
~ Creation Date 


- Creation Time 


~ Block (module relative) displacement of text blocks) 
7 Totat number of blocks consumed by the text 
~ Total number of blocks consumed by the entire module 


- Flag Field(s) 


- Record size (max record size of variable records) 


- Nee were th LANG de 
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Ae2s. DIRECTORY PARTITION 


The dicectory is a set of MIRAM indices maintained by MIRAM and 
manipulated through index-only operations ty library utilities. In- 
dices are maintained Lexicaltly ordered. Since none of the data re- 
cords are keyed, library utilities wilt be aware of tne directory en- 
tries necessary for each module and add each using en index-only 
write. 





BOG/E0G records occupy an entire block and have the same format as a 
header record (roughly) with these exceptions: 


- Group Name is the module name 
- “SOG” or “E0G” is the module name 


- Number of module blocks is set to 1 
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COMPONENT: 


MODULE: ~~~] PAGE; 





1.0 Introduction 


ie Scope SA gies BS od Ae daca wae 
This documents the CDI user interfaces to system libraries 
using library utilities. This one necessary to access or 
generate library modules and manipulate the library is 


contained here. 


The MIRAM library modules supported for the current 
release /{R7. are: aps 
Oo saved run library modules 


@ ? Oo screen format modules 
Y 


The SAT library modules supported for the current release 
are: 


Oo source ~— 


© proc 
a eT 
I, OB TET 
LO AAD 



















COMPONENT: 


MODULE: PAGE: 


e20 Functions Available 

The system library interface allows user programs to 
access directly any system library file. These functions 
are provided: 


-o xvreading a library module 


__*.o@ ereating a library module 


o deleting a librery module 


o interrogating a library directory 
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2.1 brary Interfaces 


~ 


2.1.1 anterface Macros. -. 
The CDI macros are the only ones used to interface 
with libraries (thru library utilities). Both imperative 
and declarative macros are used. The imperatives are: 
o OPEN - data management file OPEN 


© CLOSE - data management file CLOSE 


o DMINP 


retrieve a library record ‘ > 
Oo DMOUT - write a library record 

- Y : aie. 
o DMSEL - initialize a library operation {Qsually) -” 


The declaratives are: : ; & 


o cCDIB - library operation control block 


-9 RIB - usea@ only at OPEN (as per data management) 
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Flow of Control 


The CDIB (as defined by data management) is the basic 


. controlling block used by library utilities. It is used 


to communicate. between the user program and the utilities. 
It is specified on each imperative macro and will contain 


status on return. 


The user starts by issuing an OPEN imperative to a CDIB 
which identifies the library file involved (by LFD). 


This is a standard data management requirement. 


lA 


The next step depends upon what kind of operation the 
user wants to do. The operations availabie are described 


in Section 2.2 and assume the CDIB is already open. The 


_ 


flow of most operations is: 
‘1. DMSEL - initialize (or identify) operation 
2. DMINP/DMOUT - retrieve or present data 


3. DMSEL - terminate operation 


- This is an outline of a typical operation. Step 2 will 


‘ probably be executed more than once. Step 3 is not always 


required. 


The user must issue a CLOSE imperative macro for each 


CDIB active before the program terminates. 


tt ene 








ulyac 
0S/3 | 











2.2 - Reading and Writing Library tisaaies: 
This interface allows the user to read or write library 
modules a a at a time. Records of a Library- module 
are passed between library uutidetes and the user program 


as a result of a DMINP or DMOUT macro instruction. 























Reading a Library Module 


This sequence of imperative macros is required: ___ 


(0) 


. 40 EDERENG“heme-—LEPE=typel 
i. DMSEL _edib, LY, IN NEXT | -. ‘ 


(0) 
2. DMINP cdib, 
workarea 


DMSEL initializes the operation by locating the module 
——e , 


‘and returning the header record in the data buffer 


(IOAREA1). Two types of operation are permitted: 


o select element of specified name and type 


° select the next sequential element in file, 


DMINP moves data records to the user buffer. The 
i meme : 


user issues as many of these as required. When the_ 
modules is exhausted, an end of data condition is set 


in the CDIB. 


Yas Aa poe ib eal Marr 


NS eet f Fhe f 
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Writing a Library Module 

This sequence of macros ade re ees 

1. DMSEL caity, 6°bUT, BREMEN ToremerEPE=type 
g | 

2. DMOUT cdib, | workarea 


3. DMSEL cdib, LGYADD 


DMSEL (out) initializes the operation. 
DMOUT accepts user data records sequentially and adds 


them to the end of the module being generated. The 


user issues as many calls as required. 


DMSEL (ADD) completes the operation by adding the 


module to the file. All required directory indices 


are created by library utilities on this cali. if 


a module exists with the same name, it is deleted. 
When this call-is omitted, this is the result: . 
o the module is not added to the file 
© a module with the same name is not deleted 


o the integrity of the file is maintained 
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Deleting a Library Module 


To delete a library, use the aero macro: 
is 


DMSEL filename, GY DEL, waMer—CyY pe 


2.4 Interrogating a Library Directory 


(To be described in a later revision). 





Design Trade-Offs and Product Objectives 
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The goals in providing library utilities through a 


CDI interface are: 


1. 


To provide a standard interface consistant with 


other data management. interfaces. We can eventually 


allow users to use library utilities (which we never have 





had before). The interface is easily learned as it 


is a derivative of the CDI system standard. 


To provide device independence for sequential source 
INPUT/OUTPUT users. Some of the special commands 
(such as SELECT module name for input) should be 


optionally done automatically as part of OPEN. & 


- fhis would require more information on the job 


control device allocation set. It would allow 


‘users to use the sam? routine to read/write from 


either a sequential device or a library element. 














4.1 


4.1.1 





4.1.1.1 





URE 
DOCUMENTATION 





_ COMPONENT : MODULE: PAGE! 





- Interface Description 


User Interface 
Declarative Macros — 


CDIB Macro . 

The CDIB is the controlling block for any library 
operation in progress. Its use is consistent with 
the data management interface. His format is: 


filename cCDIB 


“The format of the CDIB is defined in CS-14. 
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4,001.2 RIB Macro 





a 
NAME. COPSRATION OPER 
label RIB EXC _ 
sccssoe Bi SES 616 
———___—__—— 
s | ,»BFS2Z= nn 


| [_rpasyztoi] * 
° 3 _ [. TOA=symbol| 
[ ToRc=(r) 7 A 


y P 
NO ws ple wens yar NI 


ia 


| WORK= NO 





YES 

Ha aa a a 
* Used for MIRAM library files only. 
All parameters are ovtional. Omitted parameters take 
on the underlined value. 
The INDA and ICAL narameters are not required, either. 
If they are omitted, the required space will be acquired 
‘from dynamic main storage. If they are specified, they 
are subject to the constraints: 

o For SAT library files, INDA is ignored and unused 

o For MIRAM library files, either specify both INDA 

a and IOAlL, or omit both. When you specify them, the @ 
| INDA buffer must immediately precede and be contigious 


to the TOAL puffer in main storage. oe 




























Parameters: 


ACCESS=option 


BFSZ-{ 256} 
n 


INDA=symbol 


. IOAl=symbol 


IORG=( 2 
2-12 
. r 


NWAIT={ NO 
YES 


RCSZ= { 56 
n 





Work= {ves} 


COMPONENT: 





MODULE: PAGE: 


asfineevtne disk file lock used. 

(See CS-14 for details). 

The disc buffer size (parameter IOAI1). 
It must be a multiple of 256. 


The symbolic address of the index 


_ processing buffer. It must be half- 


word aligned. Its Tengen is 256 

bytes. 

The symbolic address of the disk buffer. 
It must be halfword sidqnea. 

ris the general register used to 

point to the current eaceee when the 
user is not using a workarea. This 
parameter is ignored if aeeaues 

is specified. 

Specifies whether to eeeuen on a file 
lock error. (See CS-14 for details). 
The size of the user's work area (where 
records are returned). It should be as 
large as the largest record expected. 
Specifies whether records are to be 
placed <3 the workarea. If NO is 
specified, records will be pointed 

to by IORG. (Note: Source-records 
will only be expanded when YES is 


specified. 


















COMPONENT: MODULE: PAGE: 
4.1.2 Imperative Macros 
4.1.2.1 DMSEL Macro Format ) 
(0) 
: ADD sy : 
; DEL gases Eiendl 
DMSEL edib, LY, } IN /ELEMENT= TAG** -Typr= ( ° TAG~-..JhL. 
, NEXT 
, OUT 
ADD - add the current medule being created to the file. 


This causes the required directory indices to be 
created. (Keywords ELEMENT, TYPE do not apply). 
DEL - delete the named module from the file. This 
eliminates all directory indices for the module 
and marks the module header as inactive. r 
IN — initialize the input of the named module. (This 
| call is required before DMINP macro calls are 
permitted.) The module header record is placed 


in the buffer area. 


NEXT - initialize the input of the next module in the 
file. (This call is required before DMINP macro 
calls are permitted.) The module header is placed 
in the buffer area. 

(Note: if a BOG or ECOG is the next file item, it 
will be returned). 


OUT - initialize the output of the named module. (This 


call is required before DMOUT macro calls are ® 





permitted.) 





PAGE; 






MODULE: 


ag foctue leq ie Cael) ohare 
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 ) ‘Where a “named eoae is required, it is specified 
ae SO Sie cLeMENa-ond-TYPE. . 
, ELEMENT - the 8 character library module/group name 
- the four character library module/group name 
= contgyoes 10 byte 


quote s}-or-the tag.of the-srea—cont aining—them-may--be 


specified? 


Ce tee a, Ee 


. e «6BYPE 
ee. . 
They carbe=speciiied=as a string (¢thesaetual-neme-in 
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4515252 DM INP/DMOUT Imperative Macros 3 7 - ) 
The DMINP macro makes a record available for processing 
The DMOUT macro adds a new record to the library module 
being created, Both macros are generalized imperatives 
that can be used to request records from all data management 
processors. | 


Their format is: 








NAME ' OPERATION OPERAND 
[abe] ee oT rf workarea 
(f) 
DMOUT 1 g 
Parameters: 
cdib the symbolic address of the CDIB that 


corresponds to the similarly named Sile 
assigned through job ccntrol. 
workarea specifies a user defined ..cck area that 


will contain the record tr=::._.-> cred. 


For DMINP, a retrieved record is placed in the workarea 


if WORK=YES is specified. Otherwise the record remains 
ia 


- 


7 C 
.in the IOAl buffer and is pointed to by register IORB. 


For DMOUT, the user places records to be output in 


the workares. 








5.2 


4.3. 
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Operator Interfaces 


N/A 


Data Bases 

The proposed structure of the MIRAM library file will 
be ppessnced in an appendix: | 
The definition of the SAT library file structure 


exceeds the scope of this document. 
Environment Characteristics 


Hardware Required 


Unknown. 


Restrictions 
The MIRAM libraries (an@ library utilities) exist 
only in the CDI environment. MIRAM libraries will 


in inaccessable in the DTF only system. 


Compatibility 


N/A 


“ARM 


To be supplied. 











/ UNIYAC SOFTWARE | 
08/3 DOCUMENTATION COMPONENT: MODULE : PAGE: 
7.0 Performance . 
To be supplied. 
8.0 . Standards 
To be supplied. 
9.0 Standards Deviations 
N/A 
10.0 Documentation 
N/A 
11.0 Support 





N/A 











a 
0S 
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. Appendix A Proposed Structure for MIRAM Libraries: 


This format for MIRAM library files is based on the 


Nailos - Holt - Synder letters (10/17/78 - 11/20/78). 


Data Partition 


‘The @ata partition will consist of 256 byte fixed length 


non-keyed records. Neither deleted records nor mixed — 
keyed/non keyed records will be used. It is felt that 


neither feature is required and their inclusion would 


-yequire a one byte record control block (RCB) in each 


record. The RCB would break otherwise contiguous text 
Gata (for block modules) and unnecessarily complicate 


the design. 


A module consists of a set of uote tedeas Glows: The 
first block is the header block, which occupies cne 
full block and contains the number of blocks in the 
moadioe The next block (or blocks) contains the 
module data. All pointers within the module which 
point to blocks wieisn the module are relative to the 
module itself. Copying the module from one file to 


another can be block for block without modification. 
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The first module will be written starting in the first 


block of the data partition, followed by an ENDLIB block. 


When a second module is created, its header will be 


written in to the same block as the ENDLIB and a new 


one ENDLIB written at the end of the module. There 


“should only be one EDNLIB block in every file. 


The header block format is the same for all module 


types as well as BOG/EOG records and contains these 


fields: 


Oo: 


ce) 


Module 
Module 
Number 


Flags: 


Number 


(or group) name 


type 


of 


of 


blocks occupied by this module - 
status (deleted/active) 


index item (yes/no) 


- uniqueness (yes/no) 


blocks in module 


Block (module relative) displacement of data/ 


text blocks. 


Number of text bytes 








| PAGE: 





aac Se epee aE ts Se 


‘Directory Partition 


— The directory is a set of MIRAM indices maintained by 


MIRAM and manipulated through index-only operations by 
library utilities. Indices are maintained lexically 


ordered. Since none of the data records are keyed, 





‘library utilities will be aware of the directory 


entries necessary for each module and add each using 


an index-only write. 
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.BOG/EOG records occupy an entire block and have the same 
format a a header record (roughly) with these exceptions: 
o Group Name is the module name 
o 'BOG' or 'E0G" is the module type. 
o Number of module blocks is one 
o The unique flag is not set (allowing multiple © 


groups of the same name) 








L i.3b S$ I Q 
® Library I/0 Access routine 
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an example of the communication area 


RECORD 
NAME 


“ELTTYPE 


FUNCTION 
ERRORS 


DS 
DC 
DC 
DC 


DS: 
DC 


cLso 
C’PAYROLL 7 
C°S” 

C70" 

cui 

C717 


. 
enema 


. . . 
os ene ag Greene | Canemneemrerane & a mmonmmeanmaned 7) 





“ COHOL LANGUAGE INTERFACE 


To use LIBSIO in COBOL the user must set up a working 
storage arca definition as shown below. The Linkage with 
COBOL is done by entering linkage and calling L1IGBS10: 


ENTER LINKAGE. 
CALL LIGS10 USING LIBSIO-DATA-AREA. 
ENTER COBOL. ae 


the data area in working storage is set up similar to: 


01 LIBSIO-DATA-AREA. 


02 RECORD : PIC x(80). : ; 
C2 MONULE-NAME : PIC X€3) VALUE SPACES. 
02 MODULE-TYPE PIC x VALUE “S7~. 
; ; ; - This may be $34¢;p or mn, with . . « 
- S = source . 
; : c = copy 
p = proc : os, 
m = macro ; z 4 


G2 FUNCTION CODE ° PIC X VALUE “0%. 
this functicn code is taken 
2 from table 1. 
02 ERROR-CODE PIC X VALUE “O07. 
this is returned by LIe@sio 
it Can he Pound ta table 2+ 
FILLER PIC X VALUE “77. — 


cq) 
NI 




















we PROCESSING USING LIbSIO 


Six function ore provided by t1B8$10 which include: open 
input, open output (new), open output Cupdate) close and 
transfer. The transfer operotion ‘is used in place of a rvad 

@ or write, the type of open determines which actual function 
: will be used. The user only issues a transfer {une t1On., A 
file may be opened in either of three ways open ‘input, onen 


output (new), or open output Cupdate), any nunber, of records 
may be transferred, and the file must be closed. 
i 


FUNCTION CODE O — OPEN INPUT . : 

This “is used to- open a filé and ‘locate the 
element. It indicates that a user wishes to’ read the 
file. The file is opened, and the directory is searched 
‘for a module with the same name as that given jin the 8 
byte element name field. The user supplied 1 byte - 
module type is also used to insure ‘that the correct 
type module is located possible error codes from this 
function are: 941,252,647. | : oe 


FUNCTION CODE 2 - OPEN OUTPUT (NEW) > Sok 
hisvvfunction--is-used to initiate a new element in 


the file, when the user wishes to issue write commands. 
The file is opened as output and a module with the name 
from the 8 byte module-name area is creeted. The module 


Henn (source 
“sre SVwe ee 





» conylib, oroctib, ar macrod is determined 


: by the 14 oyte module-type fieid supplied by the user, 
7 1f the element already exists, the file is NOT opened, 
@ instcad am error condtion (4) is posted. If the user 


wishes to create an element which already exists he 
" should use function code 3 to open the files Function 

code 2 is available to  attloyr the user to prevent 

overwritina of a module which is already in the file. 


FUNCTION CODE 3 —- OPEN OUTPUT CUPDATE) 
This function code works similarly toa function 2 
except it atlows the user to overwrite an element which’ 
may exist In ‘the file. whether the element was 
contained in the file before the open or not, a nen 
element will be created and the old one, if there vas 
one, will be deleted automatically. 1f the user wants 
to know if the element existed before the creation, he 
should use an open output (new) function : : 


FUNCTION CODE 4 — TRANSFER A RECORD 
This function is used to pass 80 charecter data 
records between LIGESIO and the user. If the user has 
opened the file as input, then a transfer function is 
the same as issueing a read command. His 80 byte area 
will be loaded by LIBSIO each time he issues a 
transfer. End of file is indicated by an error code 


fe fae ae 
a ee LENNT 


fT AY oe 7 | : lee. 
Woo Bisel Tee SrisetS 








“or, af the user has opencd the file for output Ceoither 
mode) then the transfer commanc has the same effect as 
issucing a write command. He should load the 680 byte 
data area with 3a record prior to each transfer 
function. Error codes from this function art: 053-4565 75.9 


FUNCTION CODE 5 - CLOSE THE FILE : , 

This function is used to close the file after 
processing is complete. The file must be closed for 
both input and output. After the file is closed it may 
be opened again as either input or output. When a file 
is closed, no information about it’s past use is 
retained. Possible error codes from this function are: 
05556575 


Ne 





SITBSIO JNTERFACE OLSCRIPTIONS 


TABLE 14 
oe FUNCTION CODE THAT KAY. ERRCRS USE 
CODE FOLLOW IT ~ 
0 4. 6.4 2S ee OPEN INPUT 
2 4 O°. 2h 6.9 OPEN C&TPUT (NEW) 
3 4 0142 67 OPEN GUTPUT CUPDT) 
4 4 5 05679 TRANSFER 
5 02 3 0.5 6 of CLOSE 
TABLE 2 
ERROR FILE MEANING 
CODE CLOSED 
0 NO No error-h3as ocurred ~— sucessful 
1 NO Gpen attemoted on an ofen file > 
2 YES ~ File coutd not be opened (not there) aes 
3 —-- YES Element to be read could not be found 
4 YES Module to be created exists (fcn code 2) 
: ens transter (Creag/wiites oF close af 6 
: ie file which is already closed 
. te Se = OA OO, ee, : 
r @ 6 ES Unrecoverable i/o error =x 
ce ae v4 YES Error from proc module- attempt to add a 
“meme entry which exists for another proc 
i element. 
cS é E : 
& nor Function code not recognized or file type 
5 NOL SEE “to. Osh Se pe soy mi ce ; 
9 NO End of file on input file. No data is 


returned with this condition, 


RUTE: Error code U is not en actual error, ft indicates 
sucessful completion.of the function. — 7 OO ae IEE 


. 
de 











< na 
7 SESE DS 


/ . FIELD " LENGTH SUPPLIED _ USE 








a ? | BY 
OSS RECORD 80 LIBS10 Work area. for a read 
7 USER Work area for a write 
NAM Re Ge" USER Name of element to be 
“ss oS read‘or written. 
TYPE Bee e USER ' Type of element. 
FUNCTION 1 USER , Function which user: 
: x wants performed. — 
ERROR 1. LIBSIO | Error or status from 
. , Libsio ; ° 
FILE # 1 USER = ~ Must be set to “17. 


LINKING PROCEDURE 


To Link LI3BSI10 the user need only have an INCLUDE 
statement for the subroutine in his tinker job strean. A 
sample of this job strean 1s shown: . - 


Cc c 
7/ PARAHR LIN=RESVS/USERLIB 





LOAD program 
INCLUDE program,* 
INCLUDE LIBSTO,USERLIB 


* JOB CONTROL TO EXECUTE LISSI0 2 


When executing a program which uses LIBSIO, the SIAN: 
Library that is to be accessed must be defined in the job 
control -stream. This usually requires only one statement. 
The keyword ROWD=YES must be used if the file is ever opened 
as output. The library file descriptor (LFD) is LIBRARY. , 


Ti CALCAT LIGS.SRCE. peta Ur Eee hs Se Bee 
Tf ered SYSH. Los. S10 FLUM=LIBRARY 7 





WINIVAG. 


» . = 7 Bah ee Seg eS 





